               README for Tradewars 2002 bubble finder v0.09


                  Contents ..........................  1

               I. Legal Stuff .......................  2

              II. Overview ..........................  2
    
             III. Getting Sector Data ...............  3

              IV. Running the Program ...............  4

               V. Output ............................  6

              VI. Limitations .......................  7
 
             VII. Performance .......................  7

            VIII. Notes on Program Behavior .........  8

              IX. How it Works ......................  9
                                                       
               X. Compiling the Program .............  10 

              XI. Author Information ................  10

             XII. History ...........................  10





























                                   Page 1
I. Legal Stuff

This program is provided free of charge, and I'm not liable for any damage 
it may do, nor do I guarantee any level of functionality.  You know the 
drill.

The 32-bit DPMI executable is compiled with a GNU compiler, so it's 
probably subject to the GNU public license, though I'm not particularly 
inclined to wade through the documentation to find out the details.

If you make any modifications, I require that you make an effort to contact 
me before distributing the modified form.  

================================================================================

II. Overview

If you don't play the BBS online door game Tradewars 2002, then you'll find 
this particular program quite useless indeed.

If you do play, however, you may find it extremely useful.  

You may still, however, not be sure what a "bubble" in the game is.  

If you've been playing for any amount of time, you've probably come to 
realize what a tunnel is, specifically, an arrangement of sectors something 
like this:

3343
     \
2231 - 556 - 783 - 3259 - 895
     /
1011

In this case, 895 would be a dead-end sector.  Only one way in, and one 
way out.  The more sectors like 783 and 3259 between it and 556, the better.

The helper program that I use, Trade Wars Helper version 8.8, is able to 
find tunnels like the above, but it's not able to handle something like 
this:

3343               4490
     \              |
2231 - 556 - 783 - 3259 - 895
     /              |
1011               2333

TW Helper would report the above as three one-sector tunnels, whereas in 
reality is is a 5-sector bubble, with the entrance at 556.

There are two other helper programs that I know of out there, entitled TWar 
and TWATS.  TWar claims to be able to find "tunnels" with non-sequential 
sectors (which apparently covers the above), and TWATS claims to be able to 
find large bubbles.  And for all I know, they both do the job very nicely 
indeed.  But the evaluation versions are too crippled to test this feature, 
and I see no compelling reason to pay for either one, since they appear to 

                                   Page 2
do nothing that TW Helper doesn't do as well or better.  

Except for the bubble finding, of course.  After spending about 5 seconds 
deciding that TW Helper's /I and /G commands together would take too much 
time, I set out to write a program that would find bubbles automatically.

It was quite a learning experience, and it's still possible that there's 
more that I haven't thought of which will make it into a future version.

Something new to the program is finding bubbles with more than one 
entrance.  Something like the following:


3343               4490                            3234
     \              |                            /
2231 - 556 - 783 - 3259 - 895 - 443 - 559 - 1235 - 4454
     /              |               \            \
1011               2333               990 - 784    1903

The entrances in the above would be 556 and 1235.  It shouldn't take much 
imagination to see how more entrances would fit in.

See notes on program behavior for caveats with multiple-entrance bubbles.

================================================================================

III. Getting Sector Data

The way this program gets the sector information is from a file you create 
by capturing the computer CIM output in the game.  

How you do this will depend on the communications program you use.

TW Helper has an option to create TWVIEW and TWASSIST files, which for each 
includes the CIM output.  Execute the /2V command to write the *.SCT file 
that contains sector data.  This file can be used as is by the program.

If you're not using TW Helper, you can always get the information by 
creating a capture file in your communications program.  In the game, go to 
the ship computer, and enter the following sequence, using your numeric 
keypad:

ALT-200
ALT-201
ALT-202
ALT-203
ALT-204
ALT-205
ALT-206

That will put you into Computer Interrogation Mode, with a plain looking 
":" for a prompt.  At this point, turn on your capture, and press "I".

After the sector information has finished scrolling, end the capture.  This 
capture file will be what you point the program to for sector data.


                                   Page 3
The program is tolerant of junk in the file, but makes one important 
assumption:  if the line begins with a valid sector number, it considers 
the line part of the sector data.  If it isn't, junk on that line will 
cause an abort.  Other than that, lines which begin with non-numeric data 
are ignored.

================================================================================

IV. Running the Program

Once you've exported the sector data from the game, you're ready to run the 
program. 

The options are available by simply running the program without parameters, 
or with /h or /?, and are as follows:

/t  - use only one bubble route from primary entrance
/m# - minimum number of sectors in bubble; default 5
/x# - maximum number of sectors in bubble; default 50
/n# - number of sectors in universe (100 to 65535); default 1000
/e# - maximum number of entrances for bubbles (1 to 50); default 1
/p# - priority class (1 to 4); default=2 [OS/2 only]
/d# - priority delta (-31 to 31); default=-31 [OS/2 only]
/s<filename> - sector data file
/o<filename> - report file; default 'bubbles.lst'

Detailed explanations:

Option /t:  When this option is used, the program doesn't consider all 
combinations of the bubble entrance's warps as either ways back to the 
universe, or parts of the potential bubble.  Instead, it will consider only 
one warp at a time as part of the potential bubble, with all other sectors 
as ways back to the universe.  This reduces the number of iterations, 
decreasing runtime, and also prevents the situation described in the second 
note on program operation.

Option /m#:  This specifies the minimum number of sectors that a bubble 
must contain to be saved and reported.  When dead ends have been reached 
while traversing the potential bubble, if the number of sectors found 
(minus the number of entrances) is less than this number, the bubble is 
scrapped.  The default value is 5 sectors.

Option /x#:  This specifies the maximum number of sectors to traverse while 
searching for a bubble, before giving up and assuming that it's a lost 
cause.  If the number of sectors in a bubble (not counting the entrances) 
exceeds this number before all dead ends are reached, the potential bubble 
is scrapped.  The larger the number, the more potential bubbles you can 
find, but the longer the program takes to run.  Using the default will 
probably be fine for any standard game.  With Gold games, you should try a 
larger number, with multiple entrances, to find the bubble structures that 
the Gold-enabled Big Bang can be configured to create.  The largest such 
structure can be up to 19900 sectors, in a 20000-sector universe with one 
bubble allowed, so consider that when choosing this number in a Gold game.  
The default value is 50 sectors.

Option /n#:  This specifies the number of sectors in the universe.  Here is 

                                   Page 4
where the amount of storage set aside for sector information is determined.  
If the CIM file contains information for a sector number greater than this 
value, the program will abort.  The maximum value that the DOS version will 
support is 5460.  The OS/2 and DPMI versions support up to 65535 sectors
(currently, TW Gold supports only 20000 sectors).  The default value is 
1000 sectors.

Option /e#:  This specifies the number of entrances that the bubble may 
have.  There's no theoretical limit (that's less than the number of 
sectors, anyway), but practicality prompted me to put in a somewhat 
arbitrary limit of 50 entrances.  This will allow one to locate the large 
bubble structures in Gold games, which can have many entrances.  The 
default value is 1 entrance.

Option /p#:  This is specific to the OS/2 version, and specifies the 
priority class that the program runs in while searching for bubbles.  
Allowable values are integers from 1 to 4, where 1 denotes idle-class, 2 
denotes standard class, 3 denotes time-critical class, and 4 denotes 
foreground-server class.  The order of precedence, from lowest priority to 
highest, is 1-2-4-3.  This is only put into effect after the sector 
information has been loaded, and the bubble search has begun.  The idea 
here was to be able to run the program at idle priority in the background 
for a long search (for very large bubbles), while doing other things.  If 
you specify a value of 3, which is the highest priority, then a timeslice 
will be forfeited every 100 sectors, to allow you the chance to abort it 
(otherwise, keyboard input won't be processed in a timely fashion).  The 
result is that the program will run somewhat slower at time-critical 
priority than otherwise, unless there are other high-priority programs that 
are being unfriendly to the CPU.  The default value is 2.

Option /d#:  This is specific to the OS/2 version, and specifies the 
priority delta value.  This is a subdivision of the priority class, with 
valid values from -31 to 31.  Giving a value below 0 will put the priority 
slightly below other programs of the same class which have no delta, 
thereby being more friendly without going down an entire class.  Giving a 
value above 0 will put the priority slightly above other such programs, 
making this program run somewhat faster if other CPU-intensive tasks are 
running.  The default value is 0.

Option /s<filename>:  This specifies the name of the file which contains 
the CIM data capture.  There is no default, so this option must be used.

Option /o<filename>:  This specifies the name of the file which the found 
bubbles will be written to.  The specified file will be overwritten if it 
exists.  You may also use anything which the operating system can handle as 
a file, such as a named pipe, communications port, network printer name, 
etc.  The default is "bubbles.lst".

There is no space between the switch and the option data, so assuming a 
sector data file of "sectors.txt", you might do the following:

twbfind.exe /ssectors.txt /m4 /x20 /n5000 /obubbles.txt

This would read in the sector data from "sectors.txt", search for bubbles 
with a minimum of 4 sectors, and a maximum of 20 sectors, then write them 
to "bubbles.txt".

                                   Page 5

=============================================================================

V. Output

Since all output is accomplished via stream I/O, you can use anything that 
the underlying operating system can open as a file for output.  This 
includes I/O devices, such as LPT1, CON, etc.

The format of the output is this:

12-sector bubble with entrance at 2381.

Sectors in bubble:
 4051   4230   3764   2107   847   2524   2657   2683   3579   3759  
 1740   3936  

Sector  2381  -     110    1818    4051    4230  
Sector  4051  -  { 2381}  3764  
Sector  4230  -  { 2381}
Sector  3764  -    2107    4051  
Sector  2107  -     847    3764  
Sector   847  -    2107    2524    2657    2683  
Sector  2524  -     847  
Sector  2657  -     847    3579  
Sector  2683  -     847    3759  
Sector  3579  -    1740    2657  
Sector  3759  -    2683    3936  
Sector  1740  -    3579  
Sector  3936  -    3759  

--------------------------------------------------------------------------------

11-sector bubble with 2 entrances at:
  4310  3901

Sectors in bubble:
 4374   91   1846   4258   4309   3537   3230   919   2314   4505  
 3186  

Sector  4310  -  < 3975>   3439    4134    4374  
Sector  4374  -      91    1846    4258    4309  { 4310}
Sector    91  -    4374  
Sector  1846  -    3537    4374  
Sector  4258  -    3230    4374  
Sector  4309  -     919    2314    4374  
Sector  3537  -    1846  
Sector  3230  -    4258    4505  
Sector   919  -    4309  
Sector  2314  -    3186    4309  
Sector  4505  -    3230  
Sector  3186  -    2314  { 3901}
Sector  3901  -  < 3873>    623     660    1545    1969    3186  

--------------------------------------------------------------------------------


                                   Page 6
The first line says how many sectors are in the bubble, and if there's one 
entrance, displays that.  If there is more than one entrance, they are 
displayed on the second line, wrapping as needed to additional lines.

After that, the sectors in the bubble are displayed, wrapping as needed, in 
summary.

The next part is a list of all sector bubbles (including entrances, this 
time), and their warps.

Sectors surrounded by <>'s denote one-way in-warps.

Sectors surrounded by ()'s denote one-way out-warps.

Sectors surrounded by []'s denote unexplored sectors.

Sectors surrounded by {}'s denote bubble entrances.

Unembellished sectors are both out- and in-warps.

I've determined that properly displaying all the possible bubbles is 
virtually impossible with stream I/O, so a formatted display would require 
drawing a bitmap of sorts.  I might write such a thing, if I can figure out 
how, and use the data above to do it.  Anyone else might want to try the 
same thing.

Short of that, drawing on a piece of paper and connecting the lines is 
fairly easy given the above.  Those using TW Helper can do a /G command 
for a sector in the middle of the bubble to get a nice graphical layout.  
TWAR for Windows has a similar mode (currently at alpha level), and TWATS 
may very well have one as well.

For the smaller bubbles, that is.  I have found a bubble as large as 198 
sectors, with nine entrances, from a 20000-sector Gold game. Short of a 
graphical scrolling display, getting a visual grip on that one will be 
nearly impossible.

=============================================================================

VI. Limitations

The program was written to accommodate up to 65,535 sectors, since the Gold 
version of TW has currently up to 20,000.  In the unlikely event that the 
game ever exceeds 65,535 sectors, it would not be very difficult to change 
datatypes to long integers to increase capacity.  

The 16-bit DOS version has an absolute sector limit of 16382, while the 
DPMI and OS/2 executables will handle the program design limits.  As soon 
as I get Linux installed, I'll build an executable for that as well, which 
will of course not have any memory problems, either.

=============================================================================

VII. Performance

I make no pretensions about my skill as a programmer.  I'm strictly a 

                                   Page 7
novice, but I'd like to think that the program is fairly efficient, for 
what it's doing.  

The program is processor-bound, so your memory and disk subsystems are 
insignificant.  Your video subsystem may also have an impact, especially if 
running in a windowed session of whatever operating system you're using.  
Time the execution with output redirected to nul, and you'll see the 
difference.

On my Pentium II/266MHz system, with the default options for a 5000-sector 
universe, the program takes 10-15 seconds from start to finish (the DPMI 
and OS/2 versions - the DOS version is much slower).

With a maximum sector value of 200 on the same universe, the time is 
roughly one minute.

With the defaults, except for /e2 for two entrances, the program run time 
is only slightly longer.

The greater the maximum number of sectors, of course, the longer it will 
take to run.  The greater the number of entrances to search for, the longer 
it will take to run.  

================================================================================

VIII. Notes on Program Behavior

1)  The program does consider one-way exits into explored sectors the end of 
a bubble extent.  It's conceivable that such outgoing warps lead to more 
isolated sectors, something like this:

             [sector]
                |
[entrance] - [sector] - [sector] - [sector] -> [sector] 
                                                  |
                                               [sector] -> [universe]

Where -> denotes a one-way warp.  

In this case, that section between the two one-way warps would not be 
counted as part of the bubble.  However, provided there were enough such 
sectors for the given parameters, they would be part of a separate bubble 
beginning with the sector after the first one-way warp.  

I personally think that since those sectors have no path back into the 
bubble except through the universe, they shouldn't be considered part of it 
anyway.  If they did have a way back into the bubble, they'd be found and 
counted in the first place, because one-way inwarps are added to the 
bubble.

2)  Due to the way the program works, the following is considered a bubble:

           [universe]
               |
[sector] - [entrance] - [sector] - [sector] - [sector]
               |

                                   Page 8
           [universe]

Where the first sector is a single dead-end off of the entrance.  I'd 
personally not consider it part of the bubble, but I'll leave that to the 
user to decide.  The issue becomes very complex when considering the 
programmatic exclusion of such constructs.

When more than one entrance is tested for, the degree of this convolution 
can increase.  All that can be guaranteed is that all sectors reported as 
in the bubble are isolated from the universe by the entrances.

Note:  This is not applicable when using the /t option, which will not 
allow bubble sectors to be separated by the primary entrance.

=============================================================================

IX. How it Works

Here's the basic logic of how it works:

1)  For each sector, treat one or more outgoing warps as potential parts of 
a bubble with the current sector as an entrance.  Treat the rest of the 
outgoing warps as the way back to the rest of the universe. 

2)  Each possible combination of the situation in 1 should be tested.  The 
number of combinations for N outgoing warps is 2 to the Nth power minus 2 
(the two cases where either all sectors would be potential bubble members, 
or all sectors the way back to the universe).  If the /t option is used, 
then the number of combination is simply N, as only one outgoing warp is 
considered part of the potential bubble.

3)  Put each potential bubble sector into a bubble structure.

4)  Loop through the bubble structure, adding all non-oneway outgoing and 
oneway incoming warps to the end of it.  If multiple entrances are being 
checked for, then whenever the bubble cursor exceeds the minimum number of 
sectors, and the remaining sectors in the bubble do not exceed the maximum 
number of entrances, the bubble is added.  This will make for a lot of 
extra bubbles, that are later trimmed out.  The alternative approach is to 
do an outer loop for each entrance, which takes hours for two entrances, 
and hundreds of thousands of years for five entrances.

5)  If the number of sectors in the structure exceed the maximum number of 
bubble sectors to search for, abort this iteration, and go on with the next 
possible bubble structure based on the current sector.

6)  If the end of the bubble structure is reached before the max sectors 
are exceeded, that means dead-ends have been reached at all fronts, and the 
bubble is indeed isolated from the universe by the entrance.  If the number 
of sectors is larger than the minimum sectors indicated, save the bubble.

7)  After all sectors have been processed, go through all the saved 
bubbles, and eliminate any duplicates and those which are part of larger 
bubble structures.

8)  Print out the information (currently in a lame format).

                                   Page 9

================================================================================

X. Compiling the Program

The source for the program is included in the 'source.zip' archive.

The language is C++, and I've tried to make the program cross-platform, 
though it may or may not be necessary to make some small modifications 
before it will compile for you. 

There are a few defines in place that were necessary to make it compile 
under the compilers I've been using.  These may or may not need to be 
removed or altered to allow compilation on other compilers, for other 
platforms.

There's nothing sneaky going on, so just compile each .cpp file, and link 
all the objects together as one executable.  I keep separate sources for 
ease of editing.  There are makefiles for all the compilers that I used 
included.

The four included executables are:

twbfos2.exe  - 32-bit OS/2 VIO executable 
twbfdpmi.exe - 32-bit DPMI executable
twbfdos.exe  - 16-bit DOS executable (8086 instruction set)

The first was compiled with IBM VisualAge C++ 3.08 for OS/2, the second 
with the DJGPP package (a DOS port of GCC), and the third with an old copy 
of Borland C++ 3.0 for DOS.

I compiled a Win32 console version with the Mingw32 library and EGCS 
compiler, but it was too bulky and slow to be worth including.

=============================================================================

XI. Author Information

The "I" all through the rest of this file refers to me, Mike Ruskai, and I 
can be reached via e-mail to thanny@home.com, should you have a question, 
suggestion, or problem report.

=============================================================================

XII. History

10-11-98 - Initial 0.01 release.

10-13-98 - Forgot to check one memory allocation pointer, so it would crash 
           if the allocation failed.  Fixed this.

10-17-98 - Reorganized the source, putting stuff from main() into objects,
           to better facilitate any future expansion efforts.  Altered the
           output format to report all data concerning the connectivity of
           the bubble sectors, though it's not formatted to be visually
           meaningful.  Fixed an obscure glitch that would prevent some

                                   Page 10
           bubbles from being reported, due to a false assumption I made
           earlier.  Release this as version 0.02.

10-19-98 - Put a check in for duplicate sector data, so if you accidentally
           append a sector report to an existing one, instead of 
           overwriting it, the program will not get screwed up.  Release
           this as version 0.03.

10-20-98 - Fixed the comparisons to properly reflect minimum and maximum 
           sectors in bubbles.  Version 0.04, just to have a number.

10-22-98 - Got a hold of the DJGPP compiler, so we now have a DPMI 
           executable in the archive, that will handle any amount of 
           sectors.  A few minor source changes, nothing that affects
           functionality.  Call this version 0.05.

10-23-98 - Fixed stupid memory leak.  The DOS version should work OK with
           any maximum bubble size value for 5000 sectors, now, though it's 
           pretty slow doing it.  Made some source changes that should
           hopefully make it easier to compiler on other platforms.  We'll 
           call this version 0.06.

11-30-98 - Added the ability to abort a search and have all bubbles found 
           to that point trimmed and saved by pressing the space bar.

           Added priority control for the OS/2 version.  This makes it 
           possible to cripple your machine fairly well, by specifying
           priority class 3 (time critical).  Added a DosSleep() call every
           100 sectors if that's the case, so that the program can be 
           aborted.  The effect is that running with time critical will be
           slower than normal priority, unless you've a lot of 
           high-priority programs already hogging the system, in which case
           time critical priority will allow it to run normally.  The given
           priority is not set until the bubble search commences.  The 
           loading of warp information, and setting of one-way warps takes
           place at normal priority.  The idea there is to put a long 
           search at idle priority, to run in the background (/p1 /d31 is 
           the recommended setting for this).

           Added the ability to search for multiple-entrance bubbles.  This
           was inspired by the feature in TW Gold of explicitly creating
           bubbles at Big Bang, which could have several entrances.  
           There's no theoretical limit to the number of entrances that can 
           be searched for, but I've put an arbitrary limit of 50 on the 
           program, since anything above that is of extremely dubious 
           utility.

           Modified the output format to wrap lines, instead of putting 
           sectors on one long line.  

12-05-98   Gave up on the idea of including a Win32 console executable, 
           since it (compiled with EGCS using Mingw32) was too bulky and 
           slow to be of any use.  This is version 0.07.

01-08-99   Added the /t option to alter the way bubbles are searched for.
           Instead of considering all possible combinations of warps as 

                                   Page 11
           either ways back to the universe or parts of the potential 
           bubble, only one warp at a time is considered part of the 
           potential bubble.  This makes runtime a little bit faster, and 
           eliminates the possibility of finding bubbles that are split by
           the primary entrance, as explained in the second note on program 
           behavior.  This is version 0.08.

01-10-99   Changed the way sector data is stored so that the DOS version 
           now has a sector limit of 16382, instead of 5460.  Version 0.09
           will be the moniker for this puppy.















































                                   Page 13
               README for Tradewars 2002 bubble finder v0.09


                  Contents ..........................  1

               I. Legal Stuff .......................  2

              II. Overview ..........................  2
    
             III. Getting Sector Data ...............  3

              IV. Running the Program ...............  4

               V. Output ............................  6

              VI. Limitations .......................  7
 
             VII. Performance .......................  8

            VIII. Notes on Program Behavior .........  8

              IX. How it Works ......................  9
                                                       
               X. Compiling the Program .............  10 

              XI. Author Information ................  10

             XII. History ...........................  10





























                                   Page 1
I. Legal Stuff

This program is provided free of charge, and I'm not liable for any damage 
it may do, nor do I guarantee any level of functionality.  You know the 
drill.

The 32-bit DPMI executable is compiled with a GNU compiler, so it's 
probably subject to the GNU public license, though I'm not particularly 
inclined to wade through the documentation to find out the details.

If you make any modifications, I require that you make an effort to contact 
me before distributing the modified form.  

================================================================================

II. Overview

If you don't play the BBS online door game Tradewars 2002, then you'll find 
this particular program quite useless indeed.

If you do play, however, you may find it extremely useful.  

You may still, however, not be sure what a "bubble" in the game is.  

If you've been playing for any amount of time, you've probably come to 
realize what a tunnel is, specifically, an arrangement of sectors something 
like this:

3343
     \
2231 - 556 - 783 - 3259 - 895
     /
1011

In this case, 895 would be a dead-end sector.  Only one way in, and one 
way out.  The more sectors like 783 and 3259 between it and 556, the better.

The helper program that I use, Trade Wars Helper version 8.8, is able to 
find tunnels like the above, but it's not able to handle something like 
this:

3343               4490
     \              |
2231 - 556 - 783 - 3259 - 895
     /              |
1011               2333

TW Helper would report the above as three one-sector tunnels, whereas in 
reality is is a 5-sector bubble, with the entrance at 556.

There are two other helper programs that I know of out there, entitled TWar 
and TWATS.  TWar claims to be able to find "tunnels" with non-sequential 
sectors (which apparently covers the above), and TWATS claims to be able to 
find large bubbles.  And for all I know, they both do the job very nicely 
indeed.  But the evaluation versions are too crippled to test this feature, 
and I see no compelling reason to pay for either one, since they appear to 

                                   Page 2
do nothing that TW Helper doesn't do as well or better.  

Except for the bubble finding, of course.  After spending about 5 seconds 
deciding that TW Helper's /I and /G commands together would take too much 
time, I set out to write a program that would find bubbles automatically.

It was quite a learning experience, and it's still possible that there's 
more that I haven't thought of which will make it into a future version.

Something new to the program is finding bubbles with more than one 
entrance.  Something like the following:


3343               4490                            3234
     \              |                            /
2231 - 556 - 783 - 3259 - 895 - 443 - 559 - 1235 - 4454
     /              |               \            \
1011               2333               990 - 784    1903

The entrances in the above would be 556 and 1235.  It shouldn't take much 
imagination to see how more entrances would fit in.

See notes on program behavior for caveats with multiple-entrance bubbles.

================================================================================

III. Getting Sector Data

The way this program gets the sector information is from a file you create 
by capturing the computer CIM output in the game.  

How you do this will depend on the communications program you use.

TW Helper has an option to create TWVIEW and TWASSIST files, which for each 
includes the CIM output.  Execute the /2V command to write the *.SCT file 
that contains sector data.  This file can be used as is by the program.

If you're not using TW Helper, you can always get the information by 
creating a capture file in your communications program.  In the game, go to 
the ship computer, and enter the following sequence, using your numeric 
keypad:

ALT-200
ALT-201
ALT-202
ALT-203
ALT-204
ALT-205
ALT-206

That will put you into Computer Interrogation Mode, with a plain looking 
":" for a prompt.  At this point, turn on your capture, and press "I".

After the sector information has finished scrolling, end the capture.  This 
capture file will be what you point the program to for sector data.


                                   Page 3
The program is tolerant of junk in the file, but makes one important 
assumption:  if the line begins with a valid sector number, it considers 
the line part of the sector data.  If it isn't, junk on that line will 
cause an abort.  Other than that, lines which begin with non-numeric data 
are ignored.

================================================================================

IV. Running the Program

Once you've exported the sector data from the game, you're ready to run the 
program. 

The options are available by simply running the program without parameters, 
or with /h or /?, and are as follows:

/t  - use only one bubble route from primary entrance
/m# - minimum number of sectors in bubble; default 5
/x# - maximum number of sectors in bubble; default 50
/n# - number of sectors in universe (100 to 65535); default 1000
/e# - maximum number of entrances for bubbles (1 to 50); default 1
/p# - priority class (1 to 4); default=2 [OS/2 only]
/d# - priority delta (-31 to 31); default=-31 [OS/2 only]
/s<filename> - sector data file
/o<filename> - report file; default 'bubbles.lst'

Detailed explanations:

Option /t:  When this option is used, the program doesn't consider all 
combinations of the bubble entrance's warps as either ways back to the 
universe, or parts of the potential bubble.  Instead, it will consider only 
one warp at a time as part of the potential bubble, with all other sectors 
as ways back to the universe.  This reduces the number of iterations, 
decreasing runtime, and also prevents the situation described in the second 
note on program operation.

Option /m#:  This specifies the minimum number of sectors that a bubble 
must contain to be saved and reported.  When dead ends have been reached 
while traversing the potential bubble, if the number of sectors found 
(minus the number of entrances) is less than this number, the bubble is 
scrapped.  The default value is 5 sectors.

Option /x#:  This specifies the maximum number of sectors to traverse while 
searching for a bubble, before giving up and assuming that it's a lost 
cause.  If the number of sectors in a bubble (not counting the entrances) 
exceeds this number before all dead ends are reached, the potential bubble 
is scrapped.  The larger the number, the more potential bubbles you can 
find, but the longer the program takes to run.  Using the default will 
probably be fine for any standard game.  With Gold games, you should try a 
larger number, with multiple entrances, to find the bubble structures that 
the Gold-enabled Big Bang can be configured to create.  The largest such 
structure can be up to 19900 sectors, in a 20000-sector universe with one 
bubble allowed, so consider that when choosing this number in a Gold game.  
The default value is 50 sectors.

Option /n#:  This specifies the number of sectors in the universe.  Here is 

                                   Page 4
where the amount of storage set aside for sector information is determined.  
If the CIM file contains information for a sector number greater than this 
value, the program will abort.  The maximum value that the DOS version will 
support is 5460.  The OS/2 and DPMI versions support up to 65535 sectors
(currently, TW Gold supports only 20000 sectors).  The default value is 
1000 sectors.

Option /e#:  This specifies the number of entrances that the bubble may 
have.  There's no theoretical limit (that's less than the number of 
sectors, anyway), but practicality prompted me to put in a somewhat 
arbitrary limit of 50 entrances.  This will allow one to locate the large 
bubble structures in Gold games, which can have many entrances.  The 
default value is 1 entrance.

Option /p#:  This is specific to the OS/2 version, and specifies the 
priority class that the program runs in while searching for bubbles.  
Allowable values are integers from 1 to 4, where 1 denotes idle-class, 2 
denotes standard class, 3 denotes time-critical class, and 4 denotes 
foreground-server class.  The order of precedence, from lowest priority to 
highest, is 1-2-4-3.  This is only put into effect after the sector 
information has been loaded, and the bubble search has begun.  The idea 
here was to be able to run the program at idle priority in the background 
for a long search (for very large bubbles), while doing other things.  If 
you specify a value of 3, which is the highest priority, then a timeslice 
will be forfeited every 100 sectors, to allow you the chance to abort it 
(otherwise, keyboard input won't be processed in a timely fashion).  The 
result is that the program will run somewhat slower at time-critical 
priority than otherwise, unless there are other high-priority programs that 
are being unfriendly to the CPU.  The default value is 2.

Option /d#:  This is specific to the OS/2 version, and specifies the 
priority delta value.  This is a subdivision of the priority class, with 
valid values from -31 to 31.  Giving a value below 0 will put the priority 
slightly below other programs of the same class which have no delta, 
thereby being more friendly without going down an entire class.  Giving a 
value above 0 will put the priority slightly above other such programs, 
making this program run somewhat faster if other CPU-intensive tasks are 
running.  The default value is 0.

Option /s<filename>:  This specifies the name of the file which contains 
the CIM data capture.  There is no default, so this option must be used.

Option /o<filename>:  This specifies the name of the file which the found 
bubbles will be written to.  The specified file will be overwritten if it 
exists.  You may also use anything which the operating system can handle as 
a file, such as a named pipe, communications port, network printer name, 
etc.  The default is "bubbles.lst".

There is no space between the switch and the option data, so assuming a 
sector data file of "sectors.txt", you might do the following:

twbfind.exe /ssectors.txt /m4 /x20 /n5000 /obubbles.txt

This would read in the sector data from "sectors.txt", search for bubbles 
with a minimum of 4 sectors, and a maximum of 20 sectors, then write them 
to "bubbles.txt".

                                   Page 5

=============================================================================

V. Output

Since all output is accomplished via stream I/O, you can use anything that 
the underlying operating system can open as a file for output.  This 
includes I/O devices, such as LPT1, CON, etc.

The format of the output is this:

12-sector bubble with entrance at 2381.

Sectors in bubble:
 4051   4230   3764   2107   847   2524   2657   2683   3579   3759  
 1740   3936  

Sector  2381  -     110    1818    4051    4230  
Sector  4051  -  { 2381}  3764  
Sector  4230  -  { 2381}
Sector  3764  -    2107    4051  
Sector  2107  -     847    3764  
Sector   847  -    2107    2524    2657    2683  
Sector  2524  -     847  
Sector  2657  -     847    3579  
Sector  2683  -     847    3759  
Sector  3579  -    1740    2657  
Sector  3759  -    2683    3936  
Sector  1740  -    3579  
Sector  3936  -    3759  

--------------------------------------------------------------------------------

11-sector bubble with 2 entrances at:
  4310  3901

Sectors in bubble:
 4374   91   1846   4258   4309   3537   3230   919   2314   4505  
 3186  

Sector  4310  -  < 3975>   3439    4134    4374  
Sector  4374  -      91    1846    4258    4309  { 4310}
Sector    91  -    4374  
Sector  1846  -    3537    4374  
Sector  4258  -    3230    4374  
Sector  4309  -     919    2314    4374  
Sector  3537  -    1846  
Sector  3230  -    4258    4505  
Sector   919  -    4309  
Sector  2314  -    3186    4309  
Sector  4505  -    3230  
Sector  3186  -    2314  { 3901}
Sector  3901  -  < 3873>    623     660    1545    1969    3186  

--------------------------------------------------------------------------------


                                   Page 6
The first line says how many sectors are in the bubble, and if there's one 
entrance, displays that.  If there is more than one entrance, they are 
displayed on the second line, wrapping as needed to additional lines.

After that, the sectors in the bubble are displayed, wrapping as needed, in 
summary.

The next part is a list of all sector bubbles (including entrances, this 
time), and their warps.

Sectors surrounded by <>'s denote one-way in-warps.

Sectors surrounded by ()'s denote one-way out-warps.

Sectors surrounded by []'s denote unexplored sectors.

Sectors surrounded by {}'s denote bubble entrances.

Unembellished sectors are both out- and in-warps.

I've determined that properly displaying all the possible bubbles is 
virtually impossible with stream I/O, so a formatted display would require 
drawing a bitmap of sorts.  I might write such a thing, if I can figure out 
how, and use the data above to do it.  Anyone else might want to try the 
same thing.

Short of that, drawing on a piece of paper and connecting the lines is 
fairly easy given the above.  Those using TW Helper can do a /G command 
for a sector in the middle of the bubble to get a nice graphical layout.  
TWAR for Windows has a similar mode (currently at alpha level), and TWATS 
may very well have one as well.

For the smaller bubbles, that is.  I have found a bubble as large as 198 
sectors, with nine entrances, from a 20000-sector Gold game. Short of a 
graphical scrolling display, getting a visual grip on that one will be 
nearly impossible.

=============================================================================

VI. Limitations

The program was written to accommodate up to 65,535 sectors, since the Gold 
version of TW has currently up to 20,000.  In the unlikely event that the 
game ever exceeds 65,535 sectors, it would not be very difficult to change 
datatypes to long integers to increase capacity.  

The 16-bit DOS version has an absolute sector limit of 16382.  Whether it 
will run to completion depends on the available memory, the search 
parameters, and the number of bubbles in the universe matching those 
parameters.

The DPMI and OS/2 executables will handle the program design limits.  As 
soon as I get Linux installed, I'll build an executable for that as well, 
which will of course not have any memory problems, either.

=============================================================================

                                   Page 7

VII. Performance

I make no pretensions about my skill as a programmer.  I'm strictly a 
novice, but I'd like to think that the program is fairly efficient, for 
what it's doing.  

The program is processor-bound, so your memory and disk subsystems are 
insignificant.  Your video subsystem may also have an impact, especially if 
running in a windowed session of whatever operating system you're using.  
Time the execution with output redirected to nul, and you'll see the 
difference.

On my Pentium II/266MHz system, with the default options for a 5000-sector 
universe, the program takes 10-15 seconds from start to finish (the DPMI 
and OS/2 versions - the DOS version is much slower).

With a maximum sector value of 200 on the same universe, the time is 
roughly one minute.

With the defaults, except for /e2 for two entrances, the program run time 
is only slightly longer.

The greater the maximum number of sectors, of course, the longer it will 
take to run.  The greater the number of entrances to search for, the longer 
it will take to run.  

================================================================================

VIII. Notes on Program Behavior

1)  The program does consider one-way exits into explored sectors the end of 
a bubble extent.  It's conceivable that such outgoing warps lead to more 
isolated sectors, something like this:

             [sector]
                |
[entrance] - [sector] - [sector] - [sector] -> [sector] 
                                                  |
                                               [sector] -> [universe]

Where -> denotes a one-way warp.  

In this case, that section between the two one-way warps would not be 
counted as part of the bubble.  However, provided there were enough such 
sectors for the given parameters, they would be part of a separate bubble 
beginning with the sector after the first one-way warp.  

I personally think that since those sectors have no path back into the 
bubble except through the universe, they shouldn't be considered part of it 
anyway.  If they did have a way back into the bubble, they'd be found and 
counted in the first place, because one-way inwarps are added to the 
bubble.

2)  Due to the way the program works, the following is considered a bubble:


                                   Page 8
           [universe]
               |
[sector] - [entrance] - [sector] - [sector] - [sector]
               |
           [universe]

Where the first sector is a single dead-end off of the entrance.  I'd 
personally not consider it part of the bubble, but I'll leave that to the 
user to decide.  The issue becomes very complex when considering the 
programmatic exclusion of such constructs.

When more than one entrance is tested for, the degree of this convolution 
can increase.  All that can be guaranteed is that all sectors reported as 
in the bubble are isolated from the universe by the entrances.

Note:  This is not applicable when using the /t option, which will not 
allow bubble sectors to be separated by the primary entrance.

=============================================================================

IX. How it Works

Here's the basic logic of how it works:

1)  For each sector, treat one or more outgoing warps as potential parts of 
a bubble with the current sector as an entrance.  Treat the rest of the 
outgoing warps as the way back to the rest of the universe. 

2)  Each possible combination of the situation in 1 should be tested.  The 
number of combinations for N outgoing warps is 2 to the Nth power minus 2 
(the two cases where either all sectors would be potential bubble members, 
or all sectors the way back to the universe).  If the /t option is used, 
then the number of combination is simply N, as only one outgoing warp is 
considered part of the potential bubble.

3)  Put each potential bubble sector into a bubble structure.

4)  Loop through the bubble structure, adding all non-oneway outgoing and 
oneway incoming warps to the end of it.  If multiple entrances are being 
checked for, then whenever the bubble cursor exceeds the minimum number of 
sectors, and the remaining sectors in the bubble do not exceed the maximum 
number of entrances, the bubble is added.  This will make for a lot of 
extra bubbles, that are later trimmed out.  The alternative approach is to 
do an outer loop for each entrance, which takes hours for two entrances, 
and hundreds of thousands of years for five entrances.

5)  If the number of sectors in the structure exceed the maximum number of 
bubble sectors to search for, abort this iteration, and go on with the next 
possible bubble structure based on the current sector.

6)  If the end of the bubble structure is reached before the max sectors 
are exceeded, that means dead-ends have been reached at all fronts, and the 
bubble is indeed isolated from the universe by the entrance.  If the number 
of sectors is larger than the minimum sectors indicated, save the bubble.

7)  After all sectors have been processed, go through all the saved 

                                   Page 9
bubbles, and eliminate any duplicates and those which are part of larger 
bubble structures.

8)  Print out the information (currently in a lame format).

================================================================================

X. Compiling the Program

The source for the program is included in the 'source.zip' archive.

The language is C++, and I've tried to make the program cross-platform, 
though it may or may not be necessary to make some small modifications 
before it will compile for you. 

There are a few defines in place that were necessary to make it compile 
under the compilers I've been using.  These may or may not need to be 
removed or altered to allow compilation on other compilers, for other 
platforms.

There's nothing sneaky going on, so just compile each .cpp file, and link 
all the objects together as one executable.  I keep separate sources for 
ease of editing.  There are makefiles for all the compilers that I used 
included.

The four included executables are:

twbfos2.exe  - 32-bit OS/2 VIO executable 
twbfdpmi.exe - 32-bit DPMI executable
twbfdos.exe  - 16-bit DOS executable (8086 instruction set)

The first was compiled with IBM VisualAge C++ 3.08 for OS/2, the second 
with the DJGPP package (a DOS port of GCC), and the third with an old copy 
of Borland C++ 3.0 for DOS.

I compiled a Win32 console version with the Mingw32 library and EGCS 
compiler, but it was too bulky and slow to be worth including.

=============================================================================

XI. Author Information

The "I" all through the rest of this file refers to me, Mike Ruskai, and I 
can be reached via e-mail to thanny@home.com, should you have a question, 
suggestion, or problem report.

=============================================================================

XII. History

10-11-98 - Initial 0.01 release.

10-13-98 - Forgot to check one memory allocation pointer, so it would crash 
           if the allocation failed.  Fixed this.

10-17-98 - Reorganized the source, putting stuff from main() into objects,

                                   Page 10
           to better facilitate any future expansion efforts.  Altered the
           output format to report all data concerning the connectivity of
           the bubble sectors, though it's not formatted to be visually
           meaningful.  Fixed an obscure glitch that would prevent some
           bubbles from being reported, due to a false assumption I made
           earlier.  Release this as version 0.02.

10-19-98 - Put a check in for duplicate sector data, so if you accidentally
           append a sector report to an existing one, instead of 
           overwriting it, the program will not get screwed up.  Release
           this as version 0.03.

10-20-98 - Fixed the comparisons to properly reflect minimum and maximum 
           sectors in bubbles.  Version 0.04, just to have a number.

10-22-98 - Got a hold of the DJGPP compiler, so we now have a DPMI 
           executable in the archive, that will handle any amount of 
           sectors.  A few minor source changes, nothing that affects
           functionality.  Call this version 0.05.

10-23-98 - Fixed stupid memory leak.  The DOS version should work OK with
           any maximum bubble size value for 5000 sectors, now, though it's 
           pretty slow doing it.  Made some source changes that should
           hopefully make it easier to compiler on other platforms.  We'll 
           call this version 0.06.

11-30-98 - Added the ability to abort a search and have all bubbles found 
           to that point trimmed and saved by pressing the space bar.

           Added priority control for the OS/2 version.  This makes it 
           possible to cripple your machine fairly well, by specifying
           priority class 3 (time critical).  Added a DosSleep() call every
           100 sectors if that's the case, so that the program can be 
           aborted.  The effect is that running with time critical will be
           slower than normal priority, unless you've a lot of 
           high-priority programs already hogging the system, in which case
           time critical priority will allow it to run normally.  The given
           priority is not set until the bubble search commences.  The 
           loading of warp information, and setting of one-way warps takes
           place at normal priority.  The idea there is to put a long 
           search at idle priority, to run in the background (/p1 /d31 is 
           the recommended setting for this).

           Added the ability to search for multiple-entrance bubbles.  This
           was inspired by the feature in TW Gold of explicitly creating
           bubbles at Big Bang, which could have several entrances.  
           There's no theoretical limit to the number of entrances that can 
           be searched for, but I've put an arbitrary limit of 50 on the 
           program, since anything above that is of extremely dubious 
           utility.

           Modified the output format to wrap lines, instead of putting 
           sectors on one long line.  

12-05-98   Gave up on the idea of including a Win32 console executable, 
           since it (compiled with EGCS using Mingw32) was too bulky and 

                                   Page 11
           slow to be of any use.  This is version 0.07.

01-08-99   Added the /t option to alter the way bubbles are searched for.
           Instead of considering all possible combinations of warps as 
           either ways back to the universe or parts of the potential 
           bubble, only one warp at a time is considered part of the 
           potential bubble.  This makes runtime a little bit faster, and 
           eliminates the possibility of finding bubbles that are split by
           the primary entrance, as explained in the second note on program 
           behavior.  This is version 0.08.

01-11-99   Changed the way sector data is stored so that the DOS version 
           now has a sector limit of 16382, instead of 5460.  Version 0.09
           will be the moniker for this puppy.











































                                   Page 13
               README for Tradewars 2002 bubble finder v0.10


                  Contents ..........................  1

               I. Legal Stuff .......................  2

              II. Overview ..........................  2
    
             III. Getting Sector Data ...............  3

              IV. Running the Program ...............  4

               V. Output ............................  6

              VI. Limitations .......................  7
 
             VII. Performance .......................  8

            VIII. Notes on Program Behavior .........  8

              IX. How it Works ......................  9
                                                       
               X. Compiling the Program .............  10 

              XI. Author Information ................  10

             XII. History ...........................  11





























                                   Page 1
I. Legal Stuff

This program is provided free of charge, and I'm not liable for any damage 
it may do, nor do I guarantee any level of functionality.  You know the 
drill.

The 32-bit DPMI executable is compiled with a GNU compiler, so it's 
probably subject to the GNU public license, though I'm not particularly 
inclined to wade through the documentation to find out the details.

If you make any modifications, I require that you make an effort to contact 
me before distributing the modified form.  

================================================================================

II. Overview

If you don't play the BBS online door game Tradewars 2002, then you'll find 
this particular program quite useless indeed.

If you do play, however, you may find it extremely useful.  

You may still, however, not be sure what a "bubble" in the game is.  

If you've been playing for any amount of time, you've probably come to 
realize what a tunnel is, specifically, an arrangement of sectors something 
like this:

3343
     \
2231 - 556 - 783 - 3259 - 895
     /
1011

In this case, 895 would be a dead-end sector.  Only one way in, and one 
way out.  The more sectors like 783 and 3259 between it and 556, the better.

The helper program that I use, Trade Wars Helper version 8.8, is able to 
find tunnels like the above, but it's not able to handle something like 
this:

3343               4490
     \              |
2231 - 556 - 783 - 3259 - 895
     /              |
1011               2333

TW Helper would report the above as three one-sector tunnels, whereas in 
reality is is a 5-sector bubble, with the entrance at 556.

There are two other helper programs that I know of out there, entitled TWar 
and TWATS.  TWar claims to be able to find "tunnels" with non-sequential 
sectors (which apparently covers the above), and TWATS claims to be able to 
find large bubbles.  And for all I know, they both do the job very nicely 
indeed.  But the evaluation versions are too crippled to test this feature, 
and I see no compelling reason to pay for either one, since they appear to 

                                   Page 2
do nothing that TW Helper doesn't do as well or better.  

Except for the bubble finding, of course.  After spending about 5 seconds 
deciding that TW Helper's /I and /G commands together would take too much 
time, I set out to write a program that would find bubbles automatically.

It was quite a learning experience, and it's still possible that there's 
more that I haven't thought of which will make it into a future version.

Something new to the program is finding bubbles with more than one 
entrance.  Something like the following:


3343               4490                            3234
     \              |                            /
2231 - 556 - 783 - 3259 - 895 - 443 - 559 - 1235 - 4454
     /              |               \            \
1011               2333               990 - 784    1903

The entrances in the above would be 556 and 1235.  It shouldn't take much 
imagination to see how more entrances would fit in.

See notes on program behavior for caveats with multiple-entrance bubbles.

================================================================================

III. Getting Sector Data

The way this program gets the sector information is from a file you create 
by capturing the computer CIM output in the game.  

How you do this will depend on the communications program you use.

TW Helper has an option to create TWVIEW and TWASSIST files, which for each 
includes the CIM output.  Execute the /2V command to write the *.SCT file 
that contains sector data.  This file can be used as is by the program.

If you're not using TW Helper, you can always get the information by 
creating a capture file in your communications program.  In the game, go to 
the ship computer, and enter the following sequence, using your numeric 
keypad:

ALT-200
ALT-201
ALT-202
ALT-203
ALT-204
ALT-205

That will put you into Computer Interrogation Mode, with a plain looking 
":" for a prompt.  At this point, turn on your capture, and press "I".

After the sector information has finished scrolling, end the capture.  This 
capture file will be what you point the program to for sector data.

The program is tolerant of junk in the file, but makes one important 

                                   Page 3
assumption:  if the line begins with a valid sector number, it considers 
the line part of the sector data.  If it isn't, junk on that line will 
cause an abort.  Other than that, lines which begin with non-numeric data 
are ignored.

================================================================================

IV. Running the Program

Once you've exported the sector data from the game, you're ready to run the 
program. 

The options are available by simply running the program without parameters, 
or with /h or /?, and are as follows:

/t  - use only one bubble route from primary entrance
/m# - minimum number of sectors in bubble; default 5
/x# - maximum number of sectors in bubble; default 50
/n# - number of sectors in universe (100 to 65535); default 1000
/e# - maximum number of entrances for bubbles (1 to 50); default 1
/z# - entrance multiplier for minimum bubble size (2.0 to 1000.0); default 2.0
/p# - priority class (1 to 4); default=2 [OS/2 only]
/d# - priority delta (-31 to 31); default=-31 [OS/2 only]
/s<filename> - sector data file
/o<filename> - report file; default 'bubbles.lst'

Detailed explanations:

Option /t:  When this option is used, the program doesn't consider all 
combinations of the bubble entrance's warps as either ways back to the 
universe, or parts of the potential bubble.  Instead, it will consider only 
one warp at a time as part of the potential bubble, with all other sectors 
as ways back to the universe.  This reduces the number of iterations, 
decreasing runtime, and also prevents the situation described in the second 
note on program operation.

Option /m#:  This specifies the minimum number of sectors that a bubble 
must contain to be saved and reported.  When dead ends have been reached 
while traversing the potential bubble, if the number of sectors found 
(minus the number of entrances) is less than this number, the bubble is 
scrapped.  The default value is 5 sectors.

Option /x#:  This specifies the maximum number of sectors to traverse while 
searching for a bubble, before giving up and assuming that it's a lost 
cause.  If the number of sectors in a bubble (not counting the entrances) 
exceeds this number before all dead ends are reached, the potential bubble 
is scrapped.  The larger the number, the more potential bubbles you can 
find, but the longer the program takes to run.  Using the default will 
probably be fine for any standard game.  With Gold games, you should try a 
larger number, with multiple entrances, to find the bubble structures that 
the Gold-enabled Big Bang can be configured to create.  The largest such 
structure can be up to 19900 sectors, in a 20000-sector universe with one 
bubble allowed, so consider that when choosing this number in a Gold game.  
The default value is 50 sectors.

Option /n#:  This specifies the number of sectors in the universe.  Here is 

                                   Page 4
where the amount of storage set aside for sector information is determined.  
If the CIM file contains information for a sector number greater than this 
value, the program will abort.  The maximum value that the DOS version will 
support is 5460.  The OS/2 and DPMI versions support up to 65535 sectors
(currently, TW Gold supports only 20000 sectors).  The default value is 
1000 sectors.

Option /e#:  This specifies the number of entrances that the bubble may 
have.  There's no theoretical limit (that's less than the number of 
sectors, anyway), but practicality prompted me to put in a somewhat 
arbitrary limit of 50 entrances.  This will allow one to locate the large 
bubble structures in Gold games, which can have many entrances.  The 
default value is 1 entrance.

Option /z#:  This specifies how many sectors a bubble must contain relative 
to the number of entrances for it to be saved.  If the current bubble can 
be saved with 3 entrances, for example, and the value for this option is 
set to 3, then the bubble must have at least nine non-entrance sectors to 
actually be saved.  The default and minimum value is 2.  The maximum value 
is 1000 (which would, say, require 3000 sectors for a 3-entrance bubble).  
Fractional numbers are allowed, so you can specify 2.5, 7.2, etc.

Option /p#:  This is specific to the OS/2 version, and specifies the 
priority class that the program runs in while searching for bubbles.  
Allowable values are integers from 1 to 4, where 1 denotes idle-class, 2 
denotes standard class, 3 denotes time-critical class, and 4 denotes 
foreground-server class.  The order of precedence, from lowest priority to 
highest, is 1-2-4-3.  This is only put into effect after the sector 
information has been loaded, and the bubble search has begun.  The idea 
here was to be able to run the program at idle priority in the background 
for a long search (for very large bubbles), while doing other things.  If 
you specify a value of 3, which is the highest priority, then a timeslice 
will be forfeited every 100 sectors, to allow you the chance to abort it 
(otherwise, keyboard input won't be processed in a timely fashion).  The 
result is that the program will run somewhat slower at time-critical 
priority than otherwise, unless there are other high-priority programs that 
are being unfriendly to the CPU.  The default value is 2.

Option /d#:  This is specific to the OS/2 version, and specifies the 
priority delta value.  This is a subdivision of the priority class, with 
valid values from -31 to 31.  Giving a value below 0 will put the priority 
slightly below other programs of the same class which have no delta, 
thereby being more friendly without going down an entire class.  Giving a 
value above 0 will put the priority slightly above other such programs, 
making this program run somewhat faster if other CPU-intensive tasks are 
running.  The default value is 0.

Option /s<filename>:  This specifies the name of the file which contains 
the CIM data capture.  There is no default, so this option must be used.

Option /o<filename>:  This specifies the name of the file which the found 
bubbles will be written to.  The specified file will be overwritten if it 
exists.  You may also use anything which the operating system can handle as 
a file, such as a named pipe, communications port, network printer name, 
etc.  The default is "bubbles.lst".


                                   Page 5
There is no space between the switch and the option data, so assuming a 
sector data file of "sectors.txt", you might do the following:

twbfind.exe /ssectors.txt /m4 /x20 /n5000 /obubbles.txt

This would read in the sector data from "sectors.txt", search for bubbles 
with a minimum of 4 sectors, and a maximum of 20 sectors, then write them 
to "bubbles.txt".

=============================================================================

V. Output

Since all output is accomplished via stream I/O, you can use anything that 
the underlying operating system can open as a file for output.  This 
includes I/O devices, such as LPT1, CON, etc.

The format of the output is this:

12-sector bubble with entrance at 2381.

Sectors in bubble:
 4051   4230   3764   2107   847   2524   2657   2683   3579   3759  
 1740   3936  

Sector  2381  -     110    1818    4051    4230  
Sector  4051  -  { 2381}  3764  
Sector  4230  -  { 2381}
Sector  3764  -    2107    4051  
Sector  2107  -     847    3764  
Sector   847  -    2107    2524    2657    2683  
Sector  2524  -     847  
Sector  2657  -     847    3579  
Sector  2683  -     847    3759  
Sector  3579  -    1740    2657  
Sector  3759  -    2683    3936  
Sector  1740  -    3579  
Sector  3936  -    3759  

--------------------------------------------------------------------------------

11-sector bubble with 2 entrances at:
  4310  3901

Sectors in bubble:
 4374   91   1846   4258   4309   3537   3230   919   2314   4505  
 3186  

Sector  4310  -  < 3975>   3439    4134    4374  
Sector  4374  -      91    1846    4258    4309  { 4310}
Sector    91  -    4374  
Sector  1846  -    3537    4374  
Sector  4258  -    3230    4374  
Sector  4309  -     919    2314    4374  
Sector  3537  -    1846  
Sector  3230  -    4258    4505  

                                   Page 6
Sector   919  -    4309  
Sector  2314  -    3186    4309  
Sector  4505  -    3230  
Sector  3186  -    2314  { 3901}
Sector  3901  -  < 3873>    623     660    1545    1969    3186  

--------------------------------------------------------------------------------

The first line says how many sectors are in the bubble, and if there's one 
entrance, displays that.  If there is more than one entrance, they are 
displayed on the second line, wrapping as needed to additional lines.

After that, the sectors in the bubble are displayed, wrapping as needed, in 
summary.

The next part is a list of all sector bubbles (including entrances, this 
time), and their warps.

Sectors surrounded by <>'s denote one-way in-warps.

Sectors surrounded by ()'s denote one-way out-warps.

Sectors surrounded by []'s denote unexplored sectors.

Sectors surrounded by {}'s denote bubble entrances.

Unembellished sectors are both out- and in-warps.

I've determined that properly displaying all the possible bubbles is 
virtually impossible with stream I/O, so a formatted display would require 
drawing a bitmap of sorts.  I might write such a thing, if I can figure out 
how, and use the data above to do it.  Anyone else might want to try the 
same thing.

Short of that, drawing on a piece of paper and connecting the lines is 
fairly easy given the above.  Those using TW Helper can do a /G command 
for a sector in the middle of the bubble to get a nice graphical layout.  
TWAR for Windows has a similar mode (currently at alpha level), and TWATS 
may very well have one as well.

For the smaller bubbles, that is.  I have found a bubble as large as 198 
sectors, with nine entrances, from a 20000-sector Gold game. Short of a 
graphical scrolling display, getting a visual grip on that one will be 
nearly impossible.

=============================================================================

VI. Limitations

The program was written to accommodate up to 65,535 sectors, since the Gold 
version of TW has currently up to 20,000.  In the unlikely event that the 
game ever exceeds 65,535 sectors, it would not be very difficult to change 
datatypes to long integers to increase capacity.  

The 16-bit DOS version has an absolute sector limit of 16382.  Whether it 
will run to completion depends on the available memory, the search 

                                   Page 7
parameters, and the number of bubbles in the universe matching those 
parameters.

The DPMI and OS/2 executables will handle the program design limits.  As 
soon as I get Linux installed, I'll build an executable for that as well, 
which will of course not have any memory problems, either.

=============================================================================

VII. Performance

I make no pretensions about my skill as a programmer.  I'm strictly a 
novice, but I'd like to think that the program is fairly efficient, for 
what it's doing.  

The program is processor-bound, so your memory and disk subsystems are 
insignificant.  Your video subsystem may also have an impact, especially if 
running in a windowed session of whatever operating system you're using.  
Time the execution with output redirected to nul, and you'll see the 
difference.

On my Pentium II/266MHz system, with the default options for a 5000-sector 
universe, the program takes 10-15 seconds from start to finish (the DPMI 
and OS/2 versions - the DOS version is much slower).

With a maximum sector value of 200 on the same universe, the time is 
roughly one minute.

With the defaults, except for /e2 for two entrances, the program run time 
is only slightly longer.

The greater the maximum number of sectors, of course, the longer it will 
take to run.  The greater the number of entrances to search for, the longer 
it will take to run.  

================================================================================

VIII. Notes on Program Behavior

1)  The program does consider one-way exits into explored sectors the end of 
a bubble extent.  It's conceivable that such outgoing warps lead to more 
isolated sectors, something like this:

             [sector]
                |
[entrance] - [sector] - [sector] - [sector] -> [sector] 
                                                  |
                                               [sector] -> [universe]

Where -> denotes a one-way warp.  

In this case, that section between the two one-way warps would not be 
counted as part of the bubble.  However, provided there were enough such 
sectors for the given parameters, they would be part of a separate bubble 
beginning with the sector after the first one-way warp.  


                                   Page 8
I personally think that since those sectors have no path back into the 
bubble except through the universe, they shouldn't be considered part of it 
anyway.  If they did have a way back into the bubble, they'd be found and 
counted in the first place, because one-way inwarps are added to the 
bubble.

2)  Due to the way the program works, the following is considered a bubble:

           [universe]
               |
[sector] - [entrance] - [sector] - [sector] - [sector]
               |
           [universe]

Where the first sector is a single dead-end off of the entrance.  I'd 
personally not consider it part of the bubble, but I'll leave that to the 
user to decide.  The issue becomes very complex when considering the 
programmatic exclusion of such constructs.

When more than one entrance is tested for, the degree of this convolution 
can increase.  All that can be guaranteed is that all sectors reported as 
in the bubble are isolated from the universe by the entrances.

Note:  This is not applicable when using the /t option, which will not 
allow bubble sectors to be separated by the primary entrance.

=============================================================================

IX. How it Works

Here's the basic logic of how it works:

1)  For each sector, treat one or more outgoing warps as potential parts of 
a bubble with the current sector as an entrance.  Treat the rest of the 
outgoing warps as the way back to the rest of the universe. 

2)  Each possible combination of the situation in 1 should be tested.  The 
number of combinations for N outgoing warps is 2 to the Nth power minus 2 
(the two cases where either all sectors would be potential bubble members, 
or all sectors the way back to the universe).  If the /t option is used, 
then the number of combination is simply N, as only one outgoing warp is 
considered part of the potential bubble.

3)  Put each potential bubble sector into a bubble structure.

4)  Loop through the bubble structure, adding all non-oneway outgoing and 
oneway incoming warps to the end of it.  If multiple entrances are being 
checked for, then whenever the bubble cursor exceeds the minimum number of 
sectors, and the remaining sectors in the bubble do not exceed the maximum 
number of entrances, the bubble is added.  This will make for a lot of 
extra bubbles, that are later trimmed out.  The alternative approach is to 
do an outer loop for each entrance, which takes hours for two entrances, 
and hundreds of thousands of years for five entrances.

5)  If the number of sectors in the structure exceed the maximum number of 
bubble sectors to search for, abort this iteration, and go on with the next 

                                   Page 9
possible bubble structure based on the current sector.

6)  If the end of the bubble structure is reached before the max sectors 
are exceeded, that means dead-ends have been reached at all fronts, and the 
bubble is indeed isolated from the universe by the entrance.  If the number 
of sectors is larger than the minimum sectors indicated, save the bubble.

7)  After all sectors have been processed, go through all the saved 
bubbles, and eliminate any duplicates and those which are part of larger 
bubble structures.

8)  Print out the information (currently in a lame format).

================================================================================

X. Compiling the Program

The source for the program is included in the 'source.zip' archive.

The language is C++, and I've tried to make the program cross-platform, 
though it may or may not be necessary to make some small modifications 
before it will compile for you. 

There are a few defines in place that were necessary to make it compile 
under the compilers I've been using.  These may or may not need to be 
removed or altered to allow compilation on other compilers, for other 
platforms.

There's nothing sneaky going on, so just compile each .cpp file, and link 
all the objects together as one executable.  I keep separate sources for 
ease of editing.  There are makefiles for all the compilers that I used 
included.

The four included executables are:

twbfos2.exe  - 32-bit OS/2 VIO executable 
twbfdpmi.exe - 32-bit DPMI executable
twbfdos.exe  - 16-bit DOS executable (8086 instruction set)

The first was compiled with IBM VisualAge C++ 3.08 for OS/2, the second 
with the DJGPP package (a DOS port of GCC), and the third with an old copy 
of Borland C++ 3.0 for DOS.

I compiled a Win32 console version with the Mingw32 library and EGCS 
compiler, but it was too bulky and slow to be worth including.

=============================================================================

XI. Author Information

The "I" all through the rest of this file refers to me, Mike Ruskai, and I 
can be reached via e-mail to thanny@home.com, should you have a question, 
suggestion, or problem report.

=============================================================================


                                   Page 10
XII. History

10-11-98 - Initial 0.01 release.

10-13-98 - Forgot to check one memory allocation pointer, so it would crash 
           if the allocation failed.  Fixed this.

10-17-98 - Reorganized the source, putting stuff from main() into objects,
           to better facilitate any future expansion efforts.  Altered the
           output format to report all data concerning the connectivity of
           the bubble sectors, though it's not formatted to be visually
           meaningful.  Fixed an obscure glitch that would prevent some
           bubbles from being reported, due to a false assumption I made
           earlier.  Release this as version 0.02.

10-19-98 - Put a check in for duplicate sector data, so if you accidentally
           append a sector report to an existing one, instead of 
           overwriting it, the program will not get screwed up.  Release
           this as version 0.03.

10-20-98 - Fixed the comparisons to properly reflect minimum and maximum 
           sectors in bubbles.  Version 0.04, just to have a number.

10-22-98 - Got a hold of the DJGPP compiler, so we now have a DPMI 
           executable in the archive, that will handle any amount of 
           sectors.  A few minor source changes, nothing that affects
           functionality.  Call this version 0.05.

10-23-98 - Fixed stupid memory leak.  The DOS version should work OK with
           any maximum bubble size value for 5000 sectors, now, though it's 
           pretty slow doing it.  Made some source changes that should
           hopefully make it easier to compiler on other platforms.  We'll 
           call this version 0.06.

11-30-98 - Added the ability to abort a search and have all bubbles found 
           to that point trimmed and saved by pressing the space bar.

           Added priority control for the OS/2 version.  This makes it 
           possible to cripple your machine fairly well, by specifying
           priority class 3 (time critical).  Added a DosSleep() call every
           100 sectors if that's the case, so that the program can be 
           aborted.  The effect is that running with time critical will be
           slower than normal priority, unless you've a lot of 
           high-priority programs already hogging the system, in which case
           time critical priority will allow it to run normally.  The given
           priority is not set until the bubble search commences.  The 
           loading of warp information, and setting of one-way warps takes
           place at normal priority.  The idea there is to put a long 
           search at idle priority, to run in the background (/p1 /d31 is 
           the recommended setting for this).

           Added the ability to search for multiple-entrance bubbles.  This
           was inspired by the feature in TW Gold of explicitly creating
           bubbles at Big Bang, which could have several entrances.  
           There's no theoretical limit to the number of entrances that can 
           be searched for, but I've put an arbitrary limit of 50 on the 

                                   Page 11
           program, since anything above that is of extremely dubious 
           utility.

           Modified the output format to wrap lines, instead of putting 
           sectors on one long line.  

12-05-98   Gave up on the idea of including a Win32 console executable, 
           since it (compiled with EGCS using Mingw32) was too bulky and 
           slow to be of any use.  This is version 0.07.

01-08-99   Added the /t option to alter the way bubbles are searched for.
           Instead of considering all possible combinations of warps as 
           either ways back to the universe or parts of the potential 
           bubble, only one warp at a time is considered part of the 
           potential bubble.  This makes runtime a little bit faster, and 
           eliminates the possibility of finding bubbles that are split by
           the primary entrance, as explained in the second note on program 
           behavior.  This is version 0.08.

01-11-99   Changed the way sector data is stored so that the DOS version 
           now has a sector limit of 16382, instead of 5460.  Version 0.09
           will be the moniker for this puppy.

01-29-99   Replaced iterative loops with memcpy() calls, after realizing 
           that using the same pointers is not a problem.  This speeds 
           things up quite a bit when doing large searches.

           Changed the multiple-entrance support so that it wouldn't bother
           saving bubbles that didn't have twice as many sectors as the 
           number of entrances.  Then I added the /z parameter to allow the 
           user to define the multiplier (minimum is 2, maximum is 1000).  
           The result, even with just a multiplier of 2, is dramatically 
           faster multiple-entrance searches, with less garbage bubbles.  
           Setting this to a value of 10 or more will make sure that only 
           viable multiple-entrance bubbles are found, such as 20-sector 
           bubbles with 2 entrances, or 100-sector bubbles with 10 
           entrances; each being the equivalent of a single-entrance 
           10-sector bubble in terms of how much is protected per defended 
           sector.

           This is version 0.10.
















                                   Page 13
